home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 2 / CU Amiga Magazine's Super CD-ROM 02 (1996)(EMAP Images)(GB)[!][issue 1996-04].iso / magazine / amiga_e / epp / docs / pmodules / mdarray.doc < prev    next >
Text File  |  1980-01-05  |  7KB  |  222 lines
  1. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  2.                      Multi-Dimensional Arrays in E
  3.                            by Barry Wills
  4.  
  5. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  6.  
  7. Disclaimer.
  8. ~~~~~~~~~~
  9.    The user of this software assumes all risk.  This software is hereby
  10.    placed in the public domain.
  11.  
  12.  
  13. What is it?
  14. ~~~~~~~~~~
  15.    Create and use multi-dimensional arrays of any dimension in E by using
  16.    these routines.  The demos in this distribution use 3d arrays, but you
  17.    are by no means limited to these!
  18.  
  19.  
  20. Constants.
  21. ~~~~~~~~~
  22.    CONST SIZEOF_CHAR = 1
  23.    CONST SIZEOF_INT  = 2
  24.    CONST SIZEOF_LONG = 4
  25.  
  26.    These are passed into the function md_dim () via parameter elementSize.
  27.    They represent the size in bytes of the largest value which can be held
  28.    by an element of the array:  character is 1 byte, integer is 2 bytes,
  29.    long integer is 4 bytes.
  30.  
  31.  
  32. Types.
  33. ~~~~~
  34.    OBJECT md_arrayType
  35.      uBound             : LONG
  36.      elementSize        : LONG
  37.      numberOfDimensions : LONG
  38.      sizeOfDimension    : LONG
  39.      elements           : LONG
  40.    ENDOBJECT
  41.  
  42.    Declare a variable of this type for each array.  (NOTE:  If you declare a
  43.    "PTR TO md_arrayType" *YOU* must create and destroy it using New () and
  44.    Dispose() )
  45.  
  46.    The components herein are read-only!  Change the values in this object
  47.    at your own risk!  If you want to bypass the provided functions, then
  48.    study the code to see how these are used.
  49.  
  50.  
  51. Variables.
  52. ~~~~~~~~~
  53.    DEF md_constraintError = -1
  54.  
  55.    Assign to this variable the value of the exception that you want functions
  56.    md_set() and md_get() to raise if an attempt is made to access an array
  57.    out of bounds.  The default value of NIL indicates that boundary
  58.    violations will not be reported nor handled (i.e., they will be ALLOWED
  59.    to occur.)
  60.  
  61.  
  62. Functions.
  63. ~~~~~~~~~
  64. PROC md_dim (array     : PTR TO md_arrayType,
  65.              indexList : PTR TO LONG,
  66.              elementSize)
  67.  
  68.    Description.  Create private array data.
  69.    Arguments.  "array" is a static (or previously allocated) variable of type
  70.                md_arrayType.  "indexList" is a List variable of any length
  71.                which specifies the dimensions of the array.  "elementSize" is
  72.                one of the three provided constants described above.
  73.  
  74.  
  75. PROC md_set (array     : PTR TO md_arrayType,
  76.              indexList : PTR TO LONG,
  77.              value)
  78.  
  79.    Description.  Put a value into an element of the array.
  80.    Arguments.  "array" is a valid array as initialized by the function
  81.                md_dim().  "indexList" is a List variable whose length is the
  82.                same as the number of dimensions as specified by the
  83.                "indexList" passed to md_dim().  "value" is the value to be
  84.                stored in the element.
  85.  
  86.  
  87. PROC md_get (array     : PTR TO md_arrayType,
  88.              indexList : PTR TO LONG)
  89.  
  90.    Description.  Get a value from an element of the array.  This function
  91.                requires an lvalue.
  92.    Arguments.  "array" is a valid array as initialized by the function
  93.                md_dim().  "indexList" is a List variable whose length is the
  94.                same as the number of dimensions as specified by the
  95.                "indexList" passed to md_dim().
  96.  
  97.  
  98. PROC md_dispose (array : PTR TO md_arrayType)
  99.  
  100.    Description.  Deallocate private array data.
  101.    Arguments.  "array" is a valid array as initialized by the function
  102.                md_dim().
  103.  
  104.  
  105. PROC md_offset (array     : PTR TO md_arrayType,
  106.                 indexList : PTR TO LONG)
  107.  
  108.    Description.  Computes the number of bytes beyond the starting address of
  109.                  the array which correspond to the indices.  There is no
  110.                  requirement for the programmer to ever call this explicitly.
  111.    Arguments.  "array" is a valid array as initialized by the function
  112.                md_dim().  "indexList" is a List variable whose length is the
  113.                same as the number of dimensions as specified by the
  114.                "indexList" passed to md_dim().
  115.  
  116.  
  117. PROC md_withinBounds (array     : PTR TO md_arrayType,
  118.                       indexList : PTR TO LONG)
  119.  
  120.    Description.  Checks the indices to ensure that they are within bounds.
  121.                There is no requirement for the programmer to ever call this
  122.                explicitly.
  123.    Arguments.  "array" is a valid array as initialized by the function
  124.                md_dim().  "indexList" is a List variable whose length is the
  125.                same as the number of dimensions as specified by the
  126.                "indexList" passed to md_dim().
  127.  
  128.  
  129. PROC listItem (listVar : PTR TO LONG, item)
  130.  
  131.    Description.  Returns the specified element of a list.  There is no
  132.                  requirement for the programmer to ever call this explicitly.
  133.    Arguments.  "listVar" is a List variable of any length.  "item" is a LONG
  134.                value which specifies the index of "listVar".  Useful if
  135.                referencing a list in an object, e.g.,
  136.                myValue := listItem (object.list, 0).
  137.  
  138.  
  139. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  140. These are figures to show the computation of the array offset as if it were
  141. hard-coded instead of programmed.  The array offset is the number of bytes
  142. beyond the starting address of array which correspond to the indices.
  143.  
  144. NOTE:  sizeOfDimension holds the size of a single row in elements, not bytes.
  145.  
  146. 1d array, 5 characters:
  147.  
  148.   uBound             =[4]
  149.   elementSize        =[1]
  150.   numberOfDimensions =[1]
  151.   sizeOfDimension    =[1]
  152.  
  153.   [0] = (0*1) = 0
  154.   [1] = (1*1) = 1
  155.   [2] = (2*1) = 2
  156.   [3] = (3*1) = 3
  157.   [4] = (4*1) = 4
  158.  
  159.  
  160. 2d array, 2 * 3 integers:
  161.  
  162.   uBound             =[2,3]
  163.   elementSize        =[2]
  164.   numberOfDimensions =[2]
  165.   sizeOfDimension    =[3,1]
  166.  
  167.   [0,0] = (0*3) + (0*1) =  0
  168.   [0,1] = (0*3) + (1*1) =  2
  169.   [0,2] = (0*3) + (2*1) =  4
  170.   [1,0] = (1*3) + (0*1) =  6
  171.   [1,1] = (1*3) + (1*1) =  8
  172.   [1,2] = (1*3) + (2*1) = 10
  173.  
  174.  
  175. 3d array, 2 * 2 * 2 long integers:
  176.  
  177.   uBound             =[2,2,2]
  178.   elementSize        =[4]
  179.   numberOfDimensions =[3]
  180.   sizeOfDimension    =[4,2,1]
  181.  
  182.   [0,0,0] = (0*4) + (0*2) + (0*1) =  0
  183.   [0,0,1] = (0*4) + (0*2) + (1*1) =  4
  184.   [0,1,0] = (0*4) + (1*2) + (0*1) =  8
  185.   [0,1,1] = (0*4) + (1*2) + (1*1) = 12
  186.   [1,0,0] = (1*4) + (0*2) + (0*1) = 16
  187.   [1,0,1] = (1*4) + (0*2) + (1*1) = 20
  188.   [1,1,0] = (1*4) + (1*2) + (0*1) = 24
  189.   [1,1,1] = (1*4) + (1*2) + (1*1) = 28
  190.  
  191.  
  192. 3d array, 3 * 3 * 4 characters:
  193.  
  194.   uBound             =[3,3,4]
  195.   elementSize        =[1]
  196.   numberOfDimensions =[3]
  197.   sizeOfDimension    =[12,4,1]
  198.  
  199.   [0,0,0] = (0*12) + (0*4) + (0*1) =  0
  200.   [0,0,1] = (0*12) + (0*4) + (1*1) =  1
  201.   [0,0,2] = (0*12) + (0*4) + (2*1) =  2
  202.   [0,0,3] = (0*12) + (0*4) + (3*1) =  3
  203.   [0,1,0] = (0*12) + (1*4) + (0*1) =  4
  204.   [0,1,1] = (0*12) + (1*4) + (1*1) =  5
  205.   [0,1,2] = (0*12) + (1*4) + (2*1) =  6
  206.   [0,1,3] = (0*12) + (1*4) + (3*1) =  7
  207.   [0,2,0] = (0*12) + (2*4) + (0*1) =  8
  208.   [0,2,1] = (0*12) + (2*4) + (1*1) =  9
  209.   [0,2,2] = (0*12) + (2*4) + (2*1) = 10
  210.   [0,2,3] = (0*12) + (2*4) + (3*1) = 11
  211.   [1,0,0] = (1*12) + (0*4) + (0*1) = 12
  212.   [1,0,1] = (1*12) + (0*4) + (1*1) = 13
  213.   [1,0,2] = (1*12) + (0*4) + (2*1) = 14
  214.   [1,0,3] = (1*12) + (0*4) + (3*1) = 15
  215.   [1,1,0] = (1*12) + (1*4) + (0*1) = 16
  216.   [1,1,1] = (1*12) + (1*4) + (1*1) = 17
  217.   [1,1,2] = (1*12) + (1*4) + (2*1) = 18
  218.   [1,1,3] = (1*12) + (1*4) + (3*1) = 19
  219.  
  220.   ...and so on...
  221.  
  222. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~